home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacApp Release 10 / MacApp Release 10 - HD Ready / Libraries / App / Includes / UApplication.h < prev    next >
Encoding:
Text File  |  1996-04-03  |  43.8 KB  |  1,134 lines  |  [TEXT/MPS ]

  1. // UApplication.h
  2. // Copyright © 1984-96 by Apple Computer, Inc. All rights reserved.
  3.  
  4. #ifndef __UAPPLICATION__
  5. #define __UAPPLICATION__
  6.  
  7. // MacApp
  8.  
  9. #ifndef __GEOMETRY__
  10. #include "Geometry.h"
  11. #endif
  12.  
  13. #ifndef __UAPPLEEVENTS__
  14. #include "UAppleEvents.h"
  15. #endif
  16.  
  17. #ifndef __UBEHAVIOR__
  18. #include "UBehavior.h"
  19. #endif
  20.  
  21. #ifndef __UCOMMANDHANDLER__
  22. #include "UCommandHandler.h"
  23. #endif
  24.  
  25. #ifndef __UDISPATCHER__
  26. #include "UDispatcher.h"
  27. #endif
  28.  
  29. #ifndef __UGEOMETRY__
  30. #include "UGeometry.h"
  31. #endif
  32.  
  33. #ifndef __ULIST__
  34. #include "UList.h"
  35. #endif
  36.  
  37. #ifndef __ULISTITERATOR__
  38. #include "UListIterator.h"
  39. #endif
  40.  
  41. #ifndef __USCRIPTABLEOBJECT__
  42. #include "UScriptableObject.h"
  43. #endif
  44.  
  45. // Toolbox
  46.  
  47. #ifndef __BALLOONS__
  48. #include <Balloons.h>
  49. #endif
  50.  
  51. #ifndef __DIALOGS__
  52. #include <Dialogs.h>
  53. #endif
  54.  
  55. //----------------------------------------------------------------------------------------
  56. // Performance monitor menu command constants used by TApplication.
  57. //----------------------------------------------------------------------------------------
  58.  
  59. const CommandNumber cPerfMonInit = 901;
  60. const CommandNumber cPerfMonDump = 902;
  61. const CommandNumber cPerfMonToggle = 903;
  62. const CommandNumber cPerfMonEnd = 904;
  63.  
  64.  
  65. //----------------------------------------------------------------------------------------
  66. // Debugger menu command constants used by TApplication.
  67. //----------------------------------------------------------------------------------------
  68.  
  69. const CommandNumber cDebugFlags = 913;
  70. const CommandNumber cDoFirstClick = 915;            // <!> Toggle. "'Do First Click' for this
  71. const CommandNumber cRefreshFrontWindow = 917;        // <!> Action. "Refresh Front Window"
  72. const CommandNumber cSetSysJust = 921;                // <!> Action. "Switch system
  73.                                                     // justification"
  74.  
  75. //----------------------------------------------------------------------------------------
  76. // Arguments of TApplication::GetActiveWindow
  77. //----------------------------------------------------------------------------------------
  78.  
  79. //    const Boolean kFloatersOK = TRUE;
  80. //    const Boolean kNoFloaters = FALSE;
  81.  
  82. //----------------------------------------------------------------------------------------
  83. // Timeout Argument of TApplication::InteractWithUser
  84. //----------------------------------------------------------------------------------------
  85.  
  86. //    const long kMacAppTimeout = 901;    // let MacApp decide how to handle the timeout
  87.  
  88. //----------------------------------------------------------------------------------------
  89. // Forward and external class declarations. 
  90. //----------------------------------------------------------------------------------------
  91.  
  92. struct StandardFileReply;
  93. class TDocument;
  94. class TFile;
  95. class TView;
  96. class TWindow;
  97. class TEvent;
  98. class TToolboxEvent;
  99. class TMenuBarManager;
  100. class TApplication;
  101.  
  102.  
  103. //----------------------------------------------------------------------------------------
  104. // CDocumentIterator
  105. //----------------------------------------------------------------------------------------
  106.  
  107. //----------------------------------------------------------------------------------------
  108. // CNoGhostDocsIterator
  109. //----------------------------------------------------------------------------------------
  110.  
  111. //----------------------------------------------------------------------------------------
  112. //  TEventList: A list for keeping TEvents ordered by priority
  113. //----------------------------------------------------------------------------------------
  114.  
  115. #if qNeedsVU
  116.  
  117. //----------------------------------------------------------------------------------------
  118. // TVUApplication: Application with Virtual User assist
  119. //----------------------------------------------------------------------------------------
  120.  
  121. class TVUApplication : public TDispatcher
  122. {
  123.     MA_DECLARE_CLASS;
  124.     
  125. public:
  126.     TVUApplication();
  127.         // Constructor
  128.  
  129.     void IVUApplication(OSType itsMainFileType,
  130.                         OSType itsCreator);
  131.         // create the gVUAssist object
  132.         
  133.     virtual ~TVUApplication();
  134.         // Free the gVUAssist object
  135.     
  136.     virtual void AboutToLoseControl(Boolean convertClipboard);
  137.         // deactivate Mole
  138.         
  139.     virtual void RegainControl(Boolean checkClipboard);
  140.         // reactivate Mole
  141. };
  142.  
  143. #endif
  144.  
  145.  
  146. //----------------------------------------------------------------------------------------
  147. // TApplication: The purpose of this class is to implement the main event loop that all
  148. // Macintosh applications must have. There is only one instance of TApplication. One thing
  149. // that TApplication does is to interpret the raw events that are posted and convert them
  150. // into higher-level events. For example, it converts a click in the menu bar into a 'menu
  151. // event' that contains the menu ID/ item number that was chosen by the user.
  152. //----------------------------------------------------------------------------------------
  153.  
  154. #if qNeedsVU
  155. class TApplication : public TVUApplication
  156. #else
  157. class TApplication : public TDispatcher
  158. #endif
  159. {
  160.     MA_DECLARE_CLASS;
  161.     
  162. public:
  163. //    OSType fCreator;                            // The application signature; Creator type
  164.                                                 // for files.  This is used by DoMakeFile.
  165.                                                 
  166. //    OSType fMainFileType;                        // principal file type opened/printed by
  167.                                                 // application; by default,
  168.                                                 // TApplication::SFGetFilters returns a
  169.                                                 // list of just this. Used by DoMakeFile
  170.  
  171. //    TEventList* fEventList;                        // Events/Commands that were posted for
  172.                                                 // execution
  173.                                                 
  174.     
  175.     Boolean fLaunchWithNewDocument;                // True (the default) to create a new
  176.                                                 // untitled document when the application
  177.                                                 // is launched without a document.
  178.                                                 
  179. //    Boolean fAllowApplicationToSleep;            // Whether the application should be
  180.                                                 // allowed to "sleep" and thus share
  181.                                                 // processor time, when getting events
  182.  
  183. //    ProcessSerialNumber fProcessNumber;            // This application's process serial
  184.                                                 // number.
  185.  
  186. //    IdlePhase fIdlePhase;                        // The current idle phase
  187.  
  188. //    Boolean fAlwaysTrackCursor;                    // set this to true when you want the
  189.                                                 // application to track the cursor even if
  190.                                                 // it doesn't stray outside gCursorRgn.
  191.                                                 
  192. //    Boolean fDone;                                // set this to true when you want the
  193.                                                 // application to terminate
  194.  
  195. //    short fClickCount;                            // number of 'saved up' mouse clicks. If a
  196.                                                 // mouseDown, the value is that returned
  197.                                                 // by the call to
  198.                                                 // TApplication::CountClicks. If a mouseUp,
  199.                                                 // the value is left alone. Otherwise, set
  200.                                                 // to 0. Also set to 0 is the 2 clicks
  201.                                                 // were in different parts ofthe window.
  202.                                                 
  203. //    short fLastClickPart;                        // the list window part clicked in-used
  204.                                                 // for double click detection
  205.                                                 
  206. //    CPoint fLastMousePoint;                        // coordinates of mouse in last event
  207.                                                 // passed to TApplication.CountClicks
  208.                                                 
  209. //    long fLastUpTime;                            // time of last mouse up event
  210.  
  211. //    long fNextSpaceMessage;                        // time when next low space message should
  212.                                                 // be displayed
  213.                                                 
  214. //    long fLowSpaceInterval;                        // If >= 0, the frequency (in Ticks) with
  215.                                                 // which MacApp displays a low space
  216.                                                 // alert. (Defaults to kLowSpaceInterval.)
  217.                                                 // If < 0, MacApp doesn't display an
  218.                                                 // alert.
  219.                                                 
  220. //    short fMainEventMask;                        // Event mask used in main event loop.
  221.                                                 // Initialized by InitUMacApp.
  222.                                                 
  223. //    Boolean fSysWindowActive;                    // True if the front window is a system
  224.                                                 // window
  225.     
  226. //    Boolean fUndoState;                            // are we in undo or redo
  227.     
  228. //    CommandNumber fUndoCommand;
  229.     
  230. //    TList* fDocumentList;                        // list of documents
  231.     
  232. //    TList* fFreeWindowList;                        // list of free-standing (documentless)
  233.                                                 // windows
  234.     
  235. //    TEventHandler* fHeadCohandler;                // head of linked list of global
  236.                                                 // co-handlers
  237.  
  238. //    TEventHandler* fTarget;                        // the TEventHandler that gets the first
  239.                                                 // chance at DoCommand, DoSetupMenu,
  240.                                                 // DoKeyEvent, Idle; should never be NULL
  241.                                                 // -- If you do not want your own target
  242.                                                 // set this to the application object
  243.                                                 
  244. //    short fEventLevel;                            // A count of the number of nested calls
  245.                                                 // to PollToolboxEvent.
  246.                                                 
  247. //    ResNumber fDisplayedMenus;                    // menus that are read in and installed in
  248.                                                 // menu bar
  249.                                                 
  250. //    ResNumber fMBarHierarchical;                // menus that pop up when a menu item is
  251.                                                 // choosen
  252.     
  253. //    ResNumber fOtherMenus;                        // menus that are read in but not
  254.                                                 // installed
  255.     
  256. //    RgnHandle fSleepRegion;                        // the region that will be passed to
  257.                                                 // WaitNextEvent as the sleep region.
  258.                                                 // Computed from the cursor and help
  259.                                                 // regions
  260.                                                 
  261. //    RgnHandle fCursorRegion;                    // the current cursor region
  262.     
  263. //    RgnHandle fHelpRegion;                        // the current help region
  264.  
  265. //    Boolean fWantKeyUpEvents;                    // set this to true in your constructor to set
  266.                                                 // the system mask to allow key-up events
  267.  
  268. #if qDebug
  269.     TWindow* fDebugFlagsWindow;                    // Window for setting the debug flags
  270. #endif
  271.  
  272.     //------------------------------------------------------------------------------------
  273.     // Initialization and Free
  274.     //------------------------------------------------------------------------------------
  275.  
  276.     TApplication();
  277.         // Constructor
  278.     virtual ~TApplication();
  279.         // Destructor
  280.  
  281.     void IApplication(OSType itsMainFileType,
  282.                                      OSType itsCreator);
  283.         // itsMainFileType should be the 4-byte file type that this application reads and
  284.         // writes.  itsCreator is the application's signiture.  They are used when creating
  285.         // a default file with DoMakeFile and to display the proper file types in the
  286.         // StandardFile dialogs.
  287.         
  288.     virtual Boolean ChooseApplication(AEAddressDesc& theAddress);
  289.         // Choose a running application using the PPCBrowser and store the address in an
  290.         // AppleEvent address
  291.  
  292. //    virtual TMenuBarManager* MakeMenuBarManager();
  293.         // Creates an instance of TMenuBarManager
  294.     
  295.     //------------------------------------------------------------------------------------
  296.     // Event Handling
  297.     //------------------------------------------------------------------------------------
  298.  
  299. //    virtual TToolboxEvent* GetEvent(short eventMask, long sleep, 
  300. //                                            RgnHandle sleepRegion);
  301.         // Calls WaitNextEvent (or GetNextEvent) with the given event mask, sleep, and
  302.         // sleep region parameters. You can override this if you have an alternate source
  303.         // for events.
  304.  
  305. //    virtual void HandleAlienEvent(TToolboxEvent* event);
  306.         // This method is called upon to deal with 'application-specific' events
  307.  
  308. //    virtual void MainEventLoop();
  309.         // Loop on PollEvent until the application is done
  310.  
  311. //    virtual void DispatchEvent(TToolboxEvent* event);
  312.  
  313. //    virtual void DoToolboxEvent(TToolboxEvent* event);
  314.         // When this is called by MacApp, theEvent is the event to be processed.
  315.  
  316. //    virtual void DidEvent(TToolboxEvent* event);
  317.  
  318.     // Added for 3.5
  319. //    virtual void DispatchMenuEvent(TToolboxEvent* event, long menuItem);
  320.         // Handles menu events. 
  321.  
  322. //    virtual void HandleActivateEvent(TToolboxEvent* event);
  323.         // Handles activate (and deactivate) events. Calls the window's Activate method,
  324.         // and invalidates the menubar if activating the window.
  325.  
  326. //    virtual void HandleDiskEvent(TToolboxEvent* event);
  327.         // Handles disk events. Calls DIBadMount if the high word of theEvent's message is
  328.         // <> noErr
  329.  
  330. //    virtual void HandleHighLevelEvent(TToolboxEvent* event);
  331.         // Process a high level event. Default behavior is to assume it is an AppleEvent.
  332.  
  333. //    virtual void KeyEventToComponents(TToolboxEvent* event);
  334.         // re-extracts components of an event in a script manager compatible way.
  335.  
  336. //    virtual void HandleKeyDownEvent(TToolboxEvent* event);
  337.         // Handles key down events. If the command key is down, then this calls
  338.         // CommandKey. Otherwise it calls fTarget->DoKeyEvent.
  339.  
  340. //    virtual void HandleKeyUpEvent(TToolboxEvent* event);
  341.         // Handles key up events. Calls fTarget->DoKeyEvent.
  342.  
  343. //    virtual void HandleMouseDown(TToolboxEvent* event);
  344.         // Called when a mouse down occurs; this cases on whereMouseDown and does the
  345.         // right thing.
  346.  
  347. //    virtual TTracker* TrackMouse(const VPoint& theMouse, CPoint hysteresis,
  348. //                                        TTracker* theCommand);
  349.         // Responsible for mouse tracking. !!! Candidate for eventhandler method?
  350.  
  351. //    virtual void HandleMouseUp(TToolboxEvent* event);
  352.         // Sets fLastUpTime.
  353.  
  354. //    virtual void HandleSystemEvent(TToolboxEvent* event);
  355.         // Handles "system" events, in particular suspend/ resume events and mouse moved
  356.         // events. Calls RegainControl if switching in, AboutToLoseControl if switching
  357.         // out, or TrackCursor if it is a mouse-moved event.
  358.  
  359. //    virtual void HandleToolboxEvent(TToolboxEvent* event);
  360.         // Handles the dispatching of DoToolboxEvent messages between itself and Behaviors.
  361.  
  362. //    virtual void HandleUpdateEvent(TToolboxEvent* event);
  363.         // Handles window update events. Calls UpdateEvent for the window indicate by the
  364.         // event.
  365.  
  366. //    Boolean IsFrontProcess();
  367.         // Returns true if the application is currently the front process.
  368.  
  369. //    virtual void MakeFrontProcess();
  370.         // Makes this application the front process.
  371.         
  372. //    virtual void WakeProcess();
  373.         // Wakes this process if it is sleeping in WaitNextEvent. Used by callback
  374.         // procs (drag manager, apple event manager) that get called when the
  375.         // process is in a WaitNextEvent, to return from WNE and reevaluate the
  376.         // internal command que.
  377.  
  378. //    virtual void OpenDeskAccessory(const CStr255& deskAccName);
  379.         // Attempts to open the desk accessory whose name is deskAccName. Called from
  380.         // TApplication::MenuEvent when an Apple menu item is chosen, and the item has a
  381.         // negative command number.
  382.  
  383. //    virtual void PollEvent(Boolean allowApplicationToSleep);
  384.         // Polls for events/commands and processes them.
  385.  
  386. //    virtual Boolean PollToolboxEvent(Boolean allowApplicationToSleep);
  387.         // Polls for events calling Idle before waitNextEvent if there are no events
  388.         // pending and the application is allowed to go to sleep
  389.         // (kAllowApplicationToSleep), calls HandleEvent with the event, if there is one.
  390.         // and then idles if necessary.
  391.  
  392. //    void Run();
  393.         // call MainEventLoop
  394.  
  395. //    virtual void UpdateAllWindows();
  396.         // Process all update events in the queue.
  397.  
  398. //    virtual Boolean InModalState();
  399.         // Returns true if the front window is modal.
  400.  
  401. //    short GetMainEventMask();
  402.         // Retrieve the current main event mask.
  403.         
  404. //    short SetMainEventMask(short newMask);
  405.         // Set the main event mask and return the old one.
  406.  
  407.     //------------------------------------------------------------------------------------
  408.     // Target and Cohandlers
  409.     //------------------------------------------------------------------------------------
  410.  
  411. //    virtual void InstallCohandler(TEventHandler* aCohandler,
  412. //                                         Boolean addIt);
  413.         // Used to add (addIt = true) or delete (addIt = false) a cohandler to/ from the
  414.         // global list of cohandlers
  415.  
  416. //    virtual TWindow* GetFrontWindow();
  417.         // Returns the window object reference for the frontmost application window
  418.         // (whether active or not). 
  419.         // Returns NULL if the FrontWindow window is not a window object.
  420.  
  421. //    virtual TWindow* GetActiveWindow(Boolean floatersAreOkay);
  422.         // Returns the window object reference for the active application window.
  423.         // Returns NULL if the FrontWindow window is not a window object.
  424.  
  425. //    void SetTarget(TEventHandler* newTarget);
  426.         // Sets the current target (the head of the target chain) for the application.
  427.  
  428. //    TEventHandler* GetTarget();
  429.         // Returns the current target
  430.  
  431.  
  432.     //------------------------------------------------------------------------------------
  433.     // Finder Requests
  434.     //------------------------------------------------------------------------------------
  435.  
  436.     virtual Boolean CanOpenDocument(CommandNumber itsCommandNumber, TFile* aFile);
  437.         // Simulates the filtering done by Std File; this is only called when opening/
  438.         // printing documents from the finder; when using Std File, Std File does the
  439.         // filtering.
  440.  
  441.     virtual void HandleFinderRequest();
  442.         // If the AppleEvents Manager is not required or present: Gets the info from the
  443.         // finder about what files to open/ print and opens/ prints them.
  444.     
  445.  
  446.     //------------------------------------------------------------------------------------
  447.     // Opening and Printing Documents
  448.     //------------------------------------------------------------------------------------
  449.  
  450. //    virtual TDocument* FindDocument(TFile* aFile);
  451.         // Given a TFile, if that document is already opened, returns the TDocument.
  452.         // Otherwise returns NULL.
  453.  
  454.     virtual Boolean ChooseDocument(CommandNumber itsCommandNumber, TList** aFileList);
  455.         // Call this to make a Std File Get call; returns true is user selected a file.
  456.  
  457.     virtual TDocument* DoMakeDocument(CommandNumber itsCommandNumber, TFile* itsFile);
  458.         // Must be overridden. Based on itsCommandNumber create a document object of the
  459.         // appropriate kind. If itsFile <> NULL it is attached to the document
  460.  
  461. //    virtual TFile* DoMakeFile(CommandNumber itsCommandNumber);
  462.         // Default behavior is to return an instance of TFile. May be overridden to create
  463.         // a file of your own special type.
  464.  
  465.     virtual CommandNumber KindOfDocument(CommandNumber itsCommandNumber, TFile* itsFile);
  466.         // Given a command number and a specification of the file, return the command number to
  467.         // pass to DoMakeDocument that indicates the type of document to make; Default is
  468.         // to return itsCommandNumber. If you have multiple document types, a good convention
  469.         // is to return the command numbers assigned to create new documents of each kind.
  470.         // aFile will be NULL if we are creating a brand new document, rather than opening
  471.         // an existing document.
  472.  
  473.     virtual TDocument* OpenNew(CommandNumber itsCommandNumber);
  474.         // Called when the application is opened (itsCommandNumber = cFinderNew), or when NEW
  475.         // is chosen from menu (itsCommandNumber = cNew). If you do not want to create a new
  476.         // document when the user opens the application, override this and do nothing if
  477.         // itsCommandNumber = cFinderNew. Returns the document that was opened. 
  478.  
  479.     virtual TDocument* OpenOld(CommandNumber itsOpenCommand, TList* aFileList);
  480.         // Called when opening an existing document from finder (itsCommandNumber =
  481.         // cFinderOpen) or if OPEN is chosen from menu (itsCommandNumber = cOpen).
  482.         // It can also handle stationery.
  483.  
  484.     virtual void PrintDocuments(CommandNumber itsCommandNumber, TList* aFileList,
  485.                                 const FSSpec* targetPrinter = NULL);
  486.         // Called to print the documents specified from the finder.  The list of files may
  487.         // have come from a 'pdoc' AppleEvent or from HandleFinderRequest
  488.         // If targetPrinter is non-NULL it specifies a target printer for the print job
  489.  
  490.     virtual void GetStandardFileParameters(CommandNumber itsCommandNumber,
  491.                                            ProcPtr& fileFilter,
  492.                                            TypeListHandle& typeList,
  493.                                            short& dlgID,
  494.                                            CPoint& where,
  495.                                            ProcPtr& dlgHook,
  496.                                            ProcPtr& modalFilter,
  497.                                            Ptr& activeList,
  498.                                            ProcPtr& activateProc,
  499.                                            StandardFileReply* reply,
  500.                                            void*& yourDataPtr);
  501.         // Called to return all the parameters that should be passed to SFPGetFile or
  502.         // CustomGetFile, and CanOpenDocument; Defaults to:
  503.         //         dlgID = getDlgID or sfGetDialogID;
  504.         //         where = (100, 100) or (-1, -1);
  505.         //         fileFilter = NULL;
  506.         //         dlgHook = NULL;
  507.         //         modalFilter = gStandardFileFilter;
  508.         //         activeList := NULL;
  509.         //         activateProc := NULL;
  510.         //         yourDataPtr := NULL;
  511.  
  512.     virtual void GetFileTypeList(CommandNumber itsCommandNumber,
  513.                                         TypeListHandle& typeList);
  514.         // Return an valid handle to a list of file types supported by your application.
  515.         // and the number of types in the list. The default is to allocate enough space
  516.         // for fMainFileType.  Called by ChooseDocument to determine the types of files
  517.         // to display.  If no type is specified then all types are displayed.
  518.  
  519.  
  520.     //------------------------------------------------------------------------------------
  521.     // Termination
  522.     //------------------------------------------------------------------------------------
  523.  
  524. //    virtual void Close();
  525.         // Called when the user chooses Quit from the menu, and tries to save all the open
  526.         // documents. If all succeed the application terminates. Signals Failure with
  527.         // error = noErr and message = messageCancelled if user cancels
  528.  
  529.  
  530.     //------------------------------------------------------------------------------------
  531.     // Hierarchy
  532.     //------------------------------------------------------------------------------------
  533.  
  534. //    virtual void AddDocument(TDocument* aNewDocument);
  535.         // Add another document to my list of documents, and make it the current one
  536.  
  537. //    virtual void AddWindow(TWindow* aWindow);
  538.         // Add the window to the free-window list
  539.  
  540. //    virtual void DeleteDocument(TDocument* docToDelete);
  541.         // Delete a document from my list of documents
  542.  
  543. //    virtual void DeleteWindow(TWindow* windowToDelete);
  544.         // Delete a window from my list of free windows
  545.  
  546.  
  547.     //------------------------------------------------------------------------------------
  548.     // Window Manager Windows
  549.     //------------------------------------------------------------------------------------
  550.     
  551.     // Removed for 3.5
  552.     //    virtual void SelectToolboxWindow(WindowRef windowToSelect);
  553.     //        // "Selects" windowToSelect by calling the toolbox routine SelectWindow. When any
  554.     //        // window is selected, it goes through here. We never call SelectWindow directly.
  555.  
  556. //    virtual WindowRef NewToolboxWindow(Ptr storage, short rsrcId,
  557. //                                           Boolean& isResizable,
  558. //                                           Boolean& isClosable);
  559.         // Get a Window Manger window resource whose resource id is rsrId. Return
  560.         // isResizable and isClosable based upon the 'WIND' resource.
  561.  
  562. //    virtual TWindow* WMgrToWindow(WindowRef aWMgrWindow);
  563.         // Returns the window object that represents the given Window Manager window, or
  564.         // NULL if there is no window object.
  565.     
  566.  
  567.     //------------------------------------------------------------------------------------
  568.     // Idle Events
  569.     //------------------------------------------------------------------------------------
  570.     
  571. //    virtual long GetWaitTicks(Boolean allowApplicationToSleep);
  572.         // Compute the "wait ticks" to be passed to GetEvent
  573.  
  574. //    virtual void Idle(IdlePhase phase);
  575.         // Parcels out idle time to the DoIdle method in the target and cohandler chains
  576.         // of TEvtHandlers. If your application needs to do something at idle time then
  577.         // override DoIdle instead of this method.
  578.  
  579.  
  580.     //------------------------------------------------------------------------------------
  581.     // Cursor and Help
  582.     //------------------------------------------------------------------------------------
  583.     
  584. //    virtual RgnHandle GetSleepRegion();
  585.         // Return the "sleep region" to be passed to GetEvent
  586.  
  587. //    virtual void GetDefaultCursorRegion(CPoint globalMouse, RgnHandle cursorRegion);
  588.         // Computes the cursor region for the case where no window has claimed the cursor
  589.  
  590. //    virtual void InstallHelpMenuItems();
  591.         // Override this method to install your help menu item(s).  Use
  592.         // gMenuBarManager->AddHelpMenuItem( "^0 Help", kYourHelpCommandNumber );
  593.         
  594. //    virtual void GetDefaultHelpRegion(CPoint globalMouse,  RgnHandle helpRegion);
  595.         // Computes the help region for the case where no window has claimed the cursor
  596.  
  597. //    virtual void GetHelpParameters(ResNumber helpResource,
  598. //                                    short helpIndex,
  599. //                                    short helpState,
  600. //                                    HMMessageRecord& helpMessage,
  601. //                                    CPoint& localQDTip,
  602. //                                    CRect& localQDRect,
  603. //                                    short& balloonVariant);
  604.         // Gets balloon contents from an 'hdlg' resource. Called by TView::GetHelpParameters
  605.  
  606. //    virtual void DoSetCursor(CPoint globalMouse, RgnHandle cursorRegion);
  607.         // Sets the cursor to an arrow and computes the region for which it is claimed.
  608.         // Called when no view has set the cursor
  609.  
  610. //    virtual void TrackCursor(CPoint globalMouse);
  611.         // Allows windows/views to set the cursor and cursor region via TView::HandleCursor
  612.         // and TView::DoSetCursor. If no region is set, the cursor is set to an arrow and
  613.         // the largest possible default cursor region is calculated.
  614.  
  615. //    virtual void HandleCursor(CPoint globalMouse, RgnHandle cursorRegion);
  616.  
  617. //    virtual void DoShowHelp(CPoint globalMouse, RgnHandle helpRegion);
  618.         // !!!
  619.  
  620. //    virtual void TrackHelp(CPoint globalMouse);
  621.         // !!!
  622.  
  623. //    virtual void HandleHelp(CPoint globalMouse, RgnHandle helpRegion);
  624.  
  625. //    void InvalidateMouseRegions();
  626.         // Invalidates the cursor and help regions
  627.  
  628. //    void InvalidateCursorRgn();
  629.         // Sets the cursor region to the empty region
  630.  
  631. //    void InvalidateHelpRgn();
  632.         // Sets the help region to the empty region
  633.  
  634. //    virtual Boolean IsCursorRgnInvalid();
  635.         // Returns true if the cursor region needs to be recalculated
  636.  
  637. //    virtual Boolean IsHelpRgnInvalid();
  638.         // Returns true if the help region needs to be recalculated
  639.     
  640.  
  641.     //------------------------------------------------------------------------------------
  642.     // Keyboard events
  643.     //------------------------------------------------------------------------------------
  644.     
  645. //    virtual void DoKeyEvent(TToolboxEvent* event);
  646.         // Handle keydown events.
  647.  
  648.  
  649.     //------------------------------------------------------------------------------------
  650.     // Menu Events
  651.     //------------------------------------------------------------------------------------
  652.     
  653. //    virtual void DoCommandKeyEvent(TToolboxEvent* event);
  654.         // Called when a keyDown event is received and the command key is down.
  655.  
  656. //    virtual void MenuEvent(long menuItem);
  657.         // Given a value returned by MenuKey or MenuSelect, figure out the command number
  658.         // that was chosen, have the application create a command object, and post it.
  659.  
  660. //    virtual void SetUndoText(Boolean cmdDone, CommandNumber aCommandNumber);
  661.         // Called to setup the Undo menu item; if cmdDone is true it reads Undo, otherwise
  662.         // it reads Redo. aCommandNumber indicates the command that goes after the Undo/ Redo.
  663.  
  664. //    virtual void SetupTheMenus();
  665.         // Initiates the process of enabling & checking menu items.
  666.  
  667.  
  668.     //------------------------------------------------------------------------------------
  669.     // Opening and Closing Windows
  670.     //------------------------------------------------------------------------------------
  671.     
  672. //    virtual void CloseToolboxWindow(WindowRef aWMgrWindow);
  673.         // Called when user closes a window either with a menu item or with a GoAway box.
  674.         // Returns FALSE if user cancels. 
  675.         // (Used to signal Failure with error = noErr and message = messageCancelled if user cancels)
  676.  
  677.  
  678.     //------------------------------------------------------------------------------------
  679.     // Command Management
  680.     //------------------------------------------------------------------------------------
  681.     
  682. //    virtual TEvent* RetrieveAnEvent(); // Override
  683.         // Retrieves a previously posted event/ command from the queue. NULL if there are no
  684.         // queued commands.
  685.  
  686. //    virtual void ProcessEvent(TEvent* event);
  687.         // Processes the given event from the queue of event objects. The event may be a
  688.         // Toolbox event or a command object. This method calls the event's Process method.
  689.  
  690. //    virtual void PostAnEvent(TEvent* event);    // Override
  691.         // Called to post an event or command to a queue for later processing. Default is
  692.         // to hand off to fNextHandler
  693.  
  694. //    virtual void PostCommand(TCommand* command);    // Override
  695.         // Called to post a command to the queue for later execution.
  696.  
  697.     //------------------------------------------------------------------------------------
  698.     // Double/Triple Clicks
  699.     //------------------------------------------------------------------------------------
  700.     
  701. //    virtual short CountClicks(TToolboxEvent* event, short whereMouseDown);
  702.         // Called by TApplication::HandleMouseDown. Returns the number of clicks that can
  703.         // be considered multiple clicks (e.g. if it returns 1 the mouse down should be
  704.         // treated as a single click, or possibly the first click of a multi-click
  705.         // sequence. If it returns 2 the click should be considered a double-click, etc. A
  706.         // click is considered part of a multi-click sequence if the mouse down was within
  707.         // the proper time range of the previous mouse up, and was within the proper
  708.         // number of pixels of the last mouse down. TApplication::HandleMouseDown sets
  709.         // theClickCount of its EventInfo record to the result of this function.
  710.         // aPDownEvent is a pointer to the mouse down event. whereMouseDown is the result
  711.         // of FindWindow on the event.
  712.  
  713.     //------------------------------------------------------------------------------------
  714.     // Clipboard support
  715.     //------------------------------------------------------------------------------------
  716.     
  717. //    virtual void DoLaunchClipboard();
  718.         // calls gClipboardMgr->Launch
  719.  
  720. //    virtual TView* MakeViewForAlienClipboard();
  721.         // Override this to create a view to handle your application's specific data
  722.         // types. Return NULL (the default) to have the clipboard manager create a default
  723.         // view.
  724.  
  725.  
  726.     //------------------------------------------------------------------------------------
  727.     // Command Handlers
  728.     //------------------------------------------------------------------------------------
  729.     
  730.     virtual void DoMenuCommand(CommandNumber aCommandNumber);
  731.         // Handles the application specific menu commands.
  732.  
  733.     virtual void DoSetupMenus();
  734.  
  735. //    virtual void AboutToLoseControl(Boolean convertClipboard);
  736.         // Called when about to activate a Desk Accessory, switch out to another
  737.         // application, or Terminate. convertClipboard is generally true, except it will
  738.         // be false if we get a System event that does not require Clipboard conversion
  739.  
  740. //    virtual void RegainControl(Boolean checkClipboard);
  741.         // Called when switching in or when leaving a desk accessory
  742.  
  743.     virtual void DoNew(CommandNumber theCmdNumber);
  744.     // Handles the New menu item.
  745.  
  746.     virtual void DoOpen(CommandNumber theCmdNumber);
  747.     // Handles the Open menu item.
  748.  
  749.     //------------------------------------------------------------------------------------
  750.     // Error Alerts
  751.     //------------------------------------------------------------------------------------
  752.  
  753. //    virtual void Beep(short duration);
  754.         // Call this method when you want to beep at the user. Sound manager users may
  755.         // have to override this method to integrate its functionality in with your
  756.         // application
  757.  
  758. //    virtual void ShowError(OSErr error, long message);
  759.         // Calls ErrorAlert to display an error alert.
  760.  
  761. //    virtual void SpaceIsLowAlert();
  762.         // Called when space is low, at intervals of kLowSpaceInterval ticks. Displays an
  763.         // alerting informing the user that memory space is low. Override this if you wish
  764.         // to take more appropriate action.
  765.  
  766.     //------------------------------------------------------------------------------------
  767.     // AppleEvent Handling
  768.     //------------------------------------------------------------------------------------
  769.  
  770. //    virtual Boolean DoUndoRedo(TCommandHandler* theContext,
  771. //                               CommandNumber aCommandNumber,
  772. //                               MScriptableObject* theTarget);
  773.     // Handles the undo choice from the menu. If you want undo/redo to be recordable
  774.     // your DoMenuCommand method should call this on cUndo.
  775.  
  776. //    virtual Boolean UndoRedoInContext(TCommandHandler* theContext,
  777. //                                      CommandNumber aCommandNumber);
  778.     // Handles the undo event. TApplication will handle this for itself, but if
  779.     // you handle undo/redo in another context you should call this from that object's
  780.     // DoScriptCommand method.
  781.  
  782.     virtual void DoAEClose(TAppleEvent* message,
  783.                            TAppleEvent* reply);
  784.     // Handles the close event for the application.
  785.  
  786. //    #if qAttachable
  787. //        virtual Boolean HandleOSAEvent(CommandNumber aCommandNumber,
  788. //                                        TAppleEvent* message,
  789. //                                        TAppleEvent* reply);
  790. //        // Overridden to not give OSA the run AppleEvent.
  791. //    #endif
  792.  
  793.     virtual void DoScriptCommand(CommandNumber aCommandNumber,
  794.                                 TAppleEvent* message,
  795.                                 TAppleEvent* reply);
  796.     // Handles object model AppleEvents for the application.
  797.  
  798.     virtual void DoAECreateElement(TAppleEvent* message,
  799.                                    TAppleEvent* reply);
  800.     // Creates a new document. If your application has more than one type of document
  801.     // you'll need to override this method. The default simulates choosing "New" from
  802.     // the file menu.
  803.  
  804. //        virtual long CountContainedObjects(DescType desiredType);
  805. //        // Counts contained documents and window.
  806.  
  807. //        virtual MScriptableObject* GetContainedObject(DescType desiredType,
  808. //                                                      DescType selectionForm,
  809. //                                                      const CAEDesc& selectionData);
  810.  
  811. //        virtual MScriptableObject* GetIndContainedObject(DescType desiredType,
  812. //                                                         long index);
  813. //        // Returns a contained document or window.
  814.  
  815. //    virtual TWindow* GetWindowByIndex(short wIndex);
  816.     // Returns a window by front to back order.
  817.     
  818. //    virtual TWindow* GetPaletteByIndex(short index);
  819.     // Returns a palette by front to back order.
  820.  
  821. //    virtual TDocument* GetDocumentByIndex(DescType desiredType,
  822. //                                          short wIndex);
  823.     // Returns a document based on its position in the application's fDocumentList.
  824.  
  825.     //------------------------------------------------------------------------------------
  826.     // Scripting Utilities
  827.     //------------------------------------------------------------------------------------
  828.  
  829.  
  830. //    virtual Boolean MakeObjectSpecifier(CAEDesc& theObjectSpecifier,
  831. //                                     DescType preferredForm = formName);
  832.     // Creates an object specifier for the application.
  833.  
  834. //    virtual Boolean IsDocumentClass(DescType desiredType);
  835.     // If your application supports more than one document class you should override this.
  836.     // This method is then called in place of using (desiredType == cDocument).
  837.  
  838. //    virtual void ReportReplyError(CommandNumber fromCmdNum,
  839. //                                  OSErr theError,
  840. //                                  const CStr255& theErrStr);
  841.     // When a reply returned through a TSendAECommand contains an error it is sent
  842.     // through this method for reporting.
  843.  
  844.     //------------------------------------------------------------------------------------
  845.     // Application Properties
  846.     //------------------------------------------------------------------------------------
  847.  
  848. //    virtual void SetObjectProperty(const CAEDesc& thePropertyValue,
  849. //                                   DescType whichProperty);
  850.     // Sets application properties.
  851.  
  852. //    virtual Boolean GetObjectProperty(CAEDesc& thePropertyValue,
  853. //                                      DescType whichProperty,
  854. //                                      const CAEDesc& desiredType);
  855.     // Gets application properties.
  856.  
  857.     //------------------------------------------------------------------------------------
  858.     // Miscellaneous
  859.     //------------------------------------------------------------------------------------
  860.  
  861. //    virtual void DoMakeDependencySpace();
  862.         // Creates a dependency space for storing dependencies, and stores it in gMacAppDependencies.
  863.         
  864.     virtual void DoAboutBox();
  865.         // Called to show the "About the App" information
  866.  
  867. //    virtual void InvalidateFocus();
  868.         // Called to indicate that a view is unfocused when you don't know which view was focused.
  869.  
  870. //    virtual Boolean IsHelpEnabled();
  871.         // Returns true if the Help Manager is present and the user has enabled help
  872.  
  873. //    virtual OSErr InteractWithUser(NMRecPtr nmReqPtr, 
  874. //                                AEIdleUPP idleProc,
  875. //                                long timeOutInTicks = kMacAppTimeout);
  876.         // Wrapper for AEInteractWithUser. Virtual bottleneck for the Notification Manager.
  877.         
  878. //    virtual Boolean ActivateBusyCursor(Boolean entering);
  879.         // Called when the busy cursor mechanism should be activated or deactivated.
  880.  
  881. //    virtual Boolean AlertFilter(DialogRef theDialog, EventRecord& theEvent,
  882. //                                       short& itemHit);
  883.                                        
  884. //    virtual Boolean AppleEventIdleProc(EventRecord& theEventRecord,
  885. //                                              long& sleepTime,
  886. //                                               RgnHandle& mouseRgn);
  887.         // Called by the default AppleEvent idle proc MacAppAppleEventIdleProc.
  888.         // Provides default idle behavior by handling update and activate events.
  889.         
  890. //    virtual Boolean StandardFileFilter(DialogRef theDialog,
  891. //                        EventRecord& theEvent, short& itemHit, void* yourDataPtr);
  892.         // Called by the default Standard File filter proc MacAppStandardFileFilterProc.
  893.  
  894. //    virtual void DoMakeViewServer();
  895.         // instantiates the global view server
  896.         
  897. //    virtual void GetApplicationName(CStr255& theName);
  898.         // The default behavior is to return the name supplied by GetAppParms
  899. };
  900.  
  901. //----------------------------------------------------------------------------------------
  902. // TNewDocumentCommand: Tells the application open a new document.
  903. //----------------------------------------------------------------------------------------
  904.  
  905. class TNewDocumentCommand : public TCommand
  906. {
  907.     MA_DECLARE_CLASS;
  908.     
  909. public:
  910.     TNewDocumentCommand();
  911.         // Empty constructor to satisfy compiler.
  912.     virtual ~TNewDocumentCommand();
  913.         // Destructor
  914.         
  915.     void INewDocumentCommand(CommandNumber itsCommandNumber);
  916.         // Initialize the NewDocCommand procedurally.
  917.  
  918.     virtual void DoIt();
  919.         // tell the application open a new document.
  920.         
  921.     virtual TAppleEvent* MakeAppleEvent();
  922. };
  923.  
  924. //----------------------------------------------------------------------------------------
  925. // TFilesCommand: Retreives a list of files from an AppleEvent Abstract class for
  926. // TODocCommand and TPDocCommand.
  927. //----------------------------------------------------------------------------------------
  928.  
  929. class TFilesCommand : public TServerCommand
  930. {
  931.     MA_DECLARE_CLASS;
  932.     
  933. public:
  934.     TList* fFileList;
  935.  
  936. #if qPowerTalk
  937.     Boolean fOpenLetters;
  938.     CAEDesc    fLetterList;
  939. #endif // qPowerTalk
  940.     
  941.     TFilesCommand();
  942.         // Constructor
  943.         
  944.     virtual ~TFilesCommand();
  945.         // Free the list of file alias handles.
  946.  
  947.     void IFilesCommand(CommandNumber itsCommandNumber, TList* theDocuments);
  948.         // Initialize the command procedurally.
  949.  
  950.     void IFilesCommand(CommandNumber itsCommandNumber,
  951.                        const AppleEvent& itsMessage,
  952.                        const AppleEvent& itsReply);
  953.         // Initialize the command from the information contained in the Apple Event.
  954.  
  955.     void GetFilesList();
  956.         // Get the list of files from the Apple Event.
  957.  
  958. };
  959.  
  960.  
  961. //----------------------------------------------------------------------------------------
  962. // TODocCommand: Accepts a list of file aliases and opens each of them
  963. //----------------------------------------------------------------------------------------
  964.  
  965. class TODocCommand : public TFilesCommand
  966. {
  967.     MA_DECLARE_CLASS;
  968.     
  969. public:
  970.  
  971.     TODocCommand();
  972.         // Empty constructor to satisfy compiler.
  973.     virtual ~TODocCommand();
  974.         // Destructor
  975.         
  976.     void IODocCommand(CommandNumber itsCommandNumber, TList* theDocuments);
  977.         // Initialize the ODocCommand procedurally.
  978.         
  979.     void IODocCommand(CommandNumber itsCommandNumber,
  980.                       const AppleEvent& itsMessage,
  981.                       const AppleEvent& itsReply);
  982.         // Initialize the command from the information contained in the Apple Event.
  983.  
  984.     virtual void DoIt();
  985.         // Open each file found in fFileList.
  986.  
  987.     virtual TAppleEvent* MakeAppleEvent(); // Override
  988. };
  989.  
  990.  
  991. //----------------------------------------------------------------------------------------
  992. // TPDocCommand: Accepts a list of file aliases and prints each of them
  993. //----------------------------------------------------------------------------------------
  994.  
  995. class TPDocCommand : public TFilesCommand
  996. {
  997.     MA_DECLARE_CLASS;
  998.     
  999. public:
  1000.  
  1001.     TPDocCommand();
  1002.         // Constructor
  1003.     virtual ~TPDocCommand();
  1004.         // Destructor
  1005.                 
  1006.     void IPDocCommand(CommandNumber itsCommandNumber, TList* theDocuments);
  1007.         // Initialize the PDocCommand procedurally.
  1008.  
  1009.     void IPDocCommand(CommandNumber itsCommandNumber,
  1010.                       const AppleEvent& itsMessage,
  1011.                       const AppleEvent& itsReply);
  1012.         // Initialize the command from the information contained in the Apple Event.
  1013.  
  1014.     virtual void DoIt();
  1015.         // Print each file found in fFileList.
  1016.  
  1017. protected:
  1018.     FSSpec fTargetPrinter;            // The target printer if this is a "drag print"
  1019. };
  1020.  
  1021.  
  1022. //----------------------------------------------------------------------------------------
  1023. // TQuitCommand: Tells the application to do its pre-quitting stuff.
  1024. //----------------------------------------------------------------------------------------
  1025.  
  1026. class TQuitCommand : public TCommand
  1027. {
  1028.     MA_DECLARE_CLASS;
  1029.     
  1030. public:
  1031.     TQuitCommand();
  1032.         // Empty constructor to satisfy compiler.
  1033.     virtual ~TQuitCommand();
  1034.         // Destructor
  1035.     
  1036.     void IQuitCommand(CommandNumber itsCommandNumber,
  1037.                       Boolean* statusP = NULL);
  1038.     void IQuitCommand(TAppleEvent* message,
  1039.                       TAppleEvent* reply,
  1040.                       Boolean* statusP = NULL);
  1041.         // Initialize the QuitCommand procedurally.
  1042.  
  1043.     virtual Boolean IsReadyToExecute();    // Override
  1044.         // Don't let application Quit if there's a modal window open
  1045.  
  1046.     virtual void DoIt();
  1047.         // Tell the application to quit.
  1048.         
  1049.     void CloseAWindow(TWindow* aWindow);
  1050.     void CloseADocument(TDocument* aDocument);
  1051.     void DoCloseInWindowOrder();
  1052.     void DoCloseWindowlessDocuments();
  1053.     void DoCloseApplication();
  1054.         
  1055. protected:
  1056.     Boolean            fRespondingToAE;
  1057.     Boolean*        fInProcessP;
  1058.     TAppleEvent*    fMessage;
  1059.     TAppleEvent*    fReply;
  1060. };
  1061.  
  1062.  
  1063. //----------------------------------------------------------------------------------------
  1064. // TQuitAppCommand: Tells the application to quit in a recordable manner.
  1065. //     Don't issue a TQuitAppCommand to quit the application--issue a
  1066. //     TQuitCommand instead.
  1067. //----------------------------------------------------------------------------------------
  1068.  
  1069. class TQuitAppCommand : public TCommand
  1070. {
  1071.     MA_DECLARE_CLASS;
  1072.     
  1073. public:
  1074.     TQuitAppCommand();
  1075.         // Empty constructor to satisfy compiler.
  1076.     virtual ~TQuitAppCommand();
  1077.         // Destructor
  1078.         
  1079.     void IQuitAppCommand(CommandNumber itsCommandNumber);
  1080.         // Initialize the QuitAppCommand procedurally.
  1081.  
  1082.     virtual void DoIt();
  1083.         // tell the application to quit.
  1084.         
  1085.     virtual TAppleEvent* MakeAppleEvent(); // Override
  1086.  
  1087.     virtual Boolean IsReadyToExecute();    // Override
  1088.         // Don't let application Quit if there's a modal window open
  1089.  
  1090. };
  1091.  
  1092.  
  1093. //----------------------------------------------------------------------------------------
  1094. // TAboutBoxCommand: Tells the application to show its about box.
  1095. //----------------------------------------------------------------------------------------
  1096.  
  1097. class TAboutBoxCommand : public TCommand
  1098. {
  1099.     MA_DECLARE_CLASS;
  1100.     
  1101. public:
  1102.     TAboutBoxCommand();
  1103.         // Empty constructor to satisfy compiler.
  1104.     virtual ~TAboutBoxCommand();
  1105.         // Destructor
  1106.         
  1107.     void IAboutBoxCommand(CommandNumber itsCommandNumber);
  1108.         // Initialize the AboutAppCommand procedurally.
  1109.  
  1110.     virtual void DoIt();
  1111.         // tell the application to DoAboutBox.
  1112.  
  1113. };
  1114.  
  1115.  
  1116. //----------------------------------------------------------------------------------------
  1117. // TEventRetrieverCommand: Retrieve Events and process them.
  1118. //----------------------------------------------------------------------------------------
  1119.  
  1120. //----------------------------------------------------------------------------------------
  1121. // Globals defined by this unit
  1122. //----------------------------------------------------------------------------------------
  1123.  
  1124. extern TApplication* gApplication;        // the application object
  1125.  
  1126. //extern Boolean gInitialized;            // Set to true at top of TApplication::Run()
  1127.  
  1128. //extern AEAddressDesc gServerAddress;    // Address of the AppleEvent Server. Initialized
  1129.                                         // to send to ourselves.
  1130.  
  1131. #endif
  1132.  
  1133.  
  1134.